.\" -*- mode: nroff -*-
.ds V 1.5
.ds D 15/Dec/2006
.ds E " \-\- 
.if t .ds E \(em
.de Sp
.if n .sp
.if t .sp 0.4
..
.de Es
.Sp
.RS 5
.nf
..
.de Ee
.fi
.RE
.PP
..
.de Rs
.RS
.Sp
..
.de Re
.Sp
.RE
..
.de M
.BR "\\$1" "(\\$2)\\$3"
..
.de RM
.RB "\\$1" "\\$2" "(\\$3)\\$4"
..
.TH CLICK.O 8 "\*D" "Version \*V"
.SH NAME
click.o \- Click kernel module driver for Linux
'
.SH DESCRIPTION
'
The Click modular router can be compiled as a Linux kernel module, called
.BR click.o .
It can steal packets from network devices before Linux gets a chance to
handle them, send packets directly to devices, and send packets to Linux
for normal processing.
.PP
The right way to load the Click kernel module is with
.M click-install 1 ". "
This installs the module if necessary, mounts the Click file system onto
the /click directory, and installs a configuration, including any required
packages.  The right way to unload the Click kernel module is with
.M click-uninstall 1 ". "
For example:
.sp
.nf
   # click-install config.click
   # click-uninstall
.fi
'
.SH "HANDLERS"
The module's API is a filesystem similar to the
.M proc 5
filesystem.  Click creates a number of files under /click (or wherever you
have mounted the filesystem), some read-only and some read/write (writable
by the superuser). You control the module by writing to these files, which
are called
.IR handlers .
.PP
.B click-install
installs a router configuration by writing it to /click/config or
/click/hotconfig.  The configuration can use most of Click's element classes
(see
.M elements n ).
Several element classes control how the module receives and transmits
packets:
.M FromDevice n
and
.M PollDevice n
steal packets from devices before Linux processes them,
.M ToDevice n
sends packets directly to devices, and
.M ToHost n
sends packets to Linux for normal processing. Removing the module or
installing a null configuration will restore your machine's default
networking behavior.
.PP
The handlers under /click include:
.TP 5
.B /click/config
Read/write.  Contains a Click-language description (see
.M click 5 )
of the most recent router configuration, not including any run-time
reconfiguration.
.B click-install
writes a Click-language router description to this file to
install a new router configuration.
'
.TP
.B /click/hotconfig
Write-only. 
.B 'click-install -h'
writes a Click-language router description to this file to
hot-swap install a new router configuration. The new router is installed
only if it initializes correctly; otherwise, error messages will be
reported to /click/errors, but the old router will keep working
without interruption. If the new router initializes successfully, state
from the old router, such as any packets stored in
.M Queue n
elements, will be moved into the new router before it is installed. This
happens on a per-element basis, and it only works if the new element and
the old element have the same name. In contrast,
/click/config always throws away the old router.
'
.TP
.B /click/errors
Read-only. Errors reported by the Click router since the last
reconfiguration (that is, the last write to /click/config or
/click/hotconfig). Errors are also printed to the system log. Only the most
recent 2-4KB of error messages are saved in this file.
'
.TP
.B /click/messages
Read-only. All messages printed by the Click router since the last
reconfiguration (that is, the last write to /click/config or
/click/hotconfig). This includes messages generated by Print, among
others. Messages are also printed to the system log. Only the most recent
2-4KB of messages are saved in this file.
'
.TP
.B /click/classes
Read-only. The primitive element classes supported by the router, listed
one per line.
'
.TP
.B /click/list
Read-only. The names of the elements in the current router configuration,
listed one per line. The first line is an integer: the number of elements.
'
.TP
.B /click/flatconfig
Read-only. A Click-language description of the current router
configuration, including the effects of any run-time reconfiguration. All
element declarations come first, then all connections. Compound elements
are expanded into their primitive components.
'
.TP
.B /click/packages
Read-only. The packages that are currently linked to the Click module,
listed one per line.
'
.TP
.B /click/requirements
Read-only. The packages required by the current configuration, listed one
per line.
'
.TP
.B /click/cycles, /click/meminfo
Read-only. Cycle count and memory usage statistics.
'
.TP
.B /click/threads
Read-only. The PIDs of any currently running Click kernel threads, listed
one per line.
'
.TP
.B /click/priority
Read/write. The CPU priority for Click kernel threads. Lower values have
higher priority.
'
.TP
.B /click/version
Read-only. The kernel module's version number.
'
.PP
When compiled with --enable-adaptive, Click provides three additional
handlers:
'
.TP
.B /click/min_cpu_share
Read/write. The minimum fraction of CPU time Click will use, even if it has
no work to do. Expressed as a real number between 0.001 and 0.999. Default
is 0.005. Raising this number will help Click in polling mode respond more
quickly to network events.
'
.TP
.B /click/max_cpu_share
Read/write. The maximum fraction of CPU time Click will use, no matter how
much work it has to do. Expressed as a real number between 0.001 and 0.999.
Default is 0.8. Lowering this number will help user-level programs make
progress, even under high network load.
'
.TP
.B /click/cpu_share
Read-only. The fraction of CPU time Click is currently using, expressed as
a real number between 0 and 1.
'
.PP
When compiled with --enable-kassert, Click provides one additional
handler:
'
.TP
.B /click/assert_stop
Read/write. A Boolean value. If true, then Click will attempt to stop the
running router, if any, if an assertion fails. Default is false.
'
.PP
Elements with unusual names (such as "config :: Idle;") will override these
handlers with directories.  To reliably access a global handler, use the
.B /click/.h
directory, which contains only global handlers.
'
.SS "Element directories"
'
Every element in the current router configuration has a directory under
/click. You can access the directory by number or element name. The
.IR i th
element in /click/list (starting from 0) has directory
.RI `/click/.e/ i ',
and if the element is named
.IR n ,
that directory can be accessed as
.RI `/click/ n '.
This works even if the name contains slashes 
.RB ( click.o
creates directories for each name component).
.PP
Handlers in these element directories include:
'
.TP 5
.BI /click/xxx/class
Read-only. The element's class.
.TP
.BI /click/xxx/name
Read-only. The element's name.
.TP
.BI /click/xxx/config
Read/write if the element supports run-time reconfiguration; otherwise
read-only. The element's current configuration. Writing to this file (if it
is writable) causes the element to reconfigure itself on the fly. If the
reconfiguration fails, the element's old configuration is used instead.
.TP
.BI /click/xxx/ports
Read-only. Describes the element's input and output ports: how many there
are, their processing type, and (for pull inputs and push outputs) what
they are connected to.
.TP
.BI /click/xxx/handlers
Read-only. Lists the element's handlers, one per line. Each line has the
handler name and, after a tab, a permissions word. The permissions word is
currently "r" (read-only), "w" (write-only), or "rw" (read/write).
'
.PP
Elements that have associated tasks often provide these two additional
handlers:
'
.TP 5
.BI /click/xxx/scheduled
Read-only. A Boolean value: "true" if the element is currently on the task
list, "false" if it is not.
.TP
.BI /click/xxx/tickets
Read/write. Returns or sets the element's tickets, an integer that
influences task scheduling priority. The more tickets a task has, the more
often it will be scheduled relative to other tasks.
'
.PP
Particular elements may add additional handlers to their directories. For
example, RED elements (see
.M RED n )
add read/write
.BR min_thresh ", " max_thresh ", and " max_p
files representing RED parameters, and Counter elements (see
.M Counter n )
provide read-only
.BR count " and " rate
files to report packet counts and the recent rate.
.PP
Subelements with unusual names will override element-specific handlers
(consider "a, a/config :: Idle;").  To reliably access an element handler,
use the
.B /click/xxx/.h
directory, which contains element
.BR xxx 's
handlers and no subelements.
.PP
The subdirectories and generic files are always created, but
element-specific files are created only if the router configuration was
initialized successfully.
'
.SH "MANUAL LOADING"
You almost certainly should load Click using 
.M click-install 1 ". "
Nevertheless, the manual loading steps are as follows.
.TP 3
1.
Load the
.B proclikefs
module with
.M insmod 8 :
"/sbin/insmod proclikefs.ko". This module takes charge of the Click
filesystem, allowing you to safely unload the Click module even if
user-level programs have Click control files open. 
.TP
2.
Load the
.B click
module with
.BR insmod :
"/sbin/insmod click.ko".
.TP
3.
Mount the Click filesystem on a directory using
.M mount 8 ". "
The usual choice is /click: "mount -t click none /click".  The Click kernel
module installs a symbolic link from /proc/click to /click.
.TP
4.
Install a configuration by writing it to /click/config:
"cat CONFIGFILE > /click/config", for example.
.LP
To uninstall Click without
.M click-uninstall 1 ,
kill the current router by installing an empty configuration ("echo >
/click/config"), unload any element packages, and finally
.M rmmod 8
the "click" module.
'
.SH "BUGS"
If you get an unaligned access error, try running your configuration
through
.M click-align 1
before installing it.
'
.SH "SEE ALSO"
.M click 1 ,
.M click-align 1 ,
.M click-install 1 ,
.M click-uninstall 1 ,
.M insmod 1 ,
.M rmmod 1 ,
.M click 5 ,
.M elements n ,
.M FromDevice n ,
.M PollDevice n ,
.M ToDevice n ,
.M FromHost n ,
.M ToHost n ,
.M Queue n
'
.SH AUTHOR
.na
Eddie Kohler, kohler@cs.ucla.edu
.br
Robert Morris, rtm@lcs.mit.edu
.br
http://www.pdos.lcs.mit.edu/click/
'
